/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */
package com.bff.bjj.dao;

import com.bff.bjj.musicobjects.BJJAlbum;
import com.bff.bjj.musicobjects.BJJArtist;
import com.bff.bjj.musicobjects.BJJGenre;
import java.util.Collection;

/**
 *
 * @author bfindeisen
 */
public interface AlbumDao {

    /**
     * Returns a {@code Collection} of new music {@link BJJAlbum}s.  This method 
     * does not populate the artist field so an additional call is necessary if you 
     * need that field later on.
     *
     * Use {@link getAlbums(boolean) if you with to populate the artist field.
     *
     * @return a {@code Collection} of all {@link BJJAlbum}s
     */
    public Collection<BJJAlbum> getNewMusic();

    /**
     * Returns the total number of albums
     *
     * @return the number of albums
     * @throws BJJException if there is a problem getting the count
     */
    public int getAlbumCount();    

    /**
     * Returns a <CODE>Collection</CODE> of {@link BJJAlbum}s for an {@link BJJArtist}
     *
     * @param artist the {@link BJJArtist} to match
     * @return a <CODE>Collection</CODE> of {@link BJJAlbum}s
     * @throws BJJDatabaseException if there is a database problem
     */
    public Collection<BJJAlbum> listAlbumsForArtist(BJJArtist artist);

    /**
     * Returns a <CODE>Collection</CODE> of {@link BJJAlbum}s for a year
     *
     * @param artist {@link BJJArtist} to match
     * @return a <CODE>Collection</CODE> of {@link BJJAlbum}s
     * @throws BJJDatabaseException if there is a database problem
     */
    public Collection<BJJAlbum> listAlbumsForYear(String year);

    /**
     * Returns a <CODE>Collection</CODE> of {@link BJJAlbum}s for an {@link BJJGenre}
     *
     * @param artist {@link BJJGenre} to match
     * @return a <CODE>Collection</CODE> of {@link BJJAlbum}s
     * @throws BJJDatabaseException if there is a database problem
     */
    public Collection<BJJAlbum> listAlbumsForGenre(BJJGenre genre);

    /**
     * Lists the albums for the passed criteria. Pass null to match all.
     *
     * @param artist the @{link BJJArtist} to match
     * @param genre the @{link BJJGenre} to match
     * @param year the year to match
     * @return a <CODE>Collection</CODE> of {@link BJJAlbum}s
     * @throws BJJDatabaseException if there is a database problem
     */
    public Collection<BJJAlbum> listAlbums(BJJArtist artist, BJJGenre genre, String year);
    /**
     * Returns a {@code Collection} of all {@link BJJAlbum}s.  This method does not populate
     * the artist field so an additional call is necessary if you need that field later on.
     *
     * Use {@link getAlbums(boolean) if you with to populate the artist field.
     *
     * @return a {@code Collection} of all {@link BJJAlbum}s
     */
    public Collection<BJJAlbum> getAlbums();

    /**
     * Returns a {@code Collection} of all {@link BJJAlbum}s include the artist name 
     * associated with the album.  Passing true slightly affects the performance of the lookup.
     * @param includeArtist
     * @return a {@code Collection} of all {@link BJJAlbum}s
     */
    public Collection<BJJAlbum> getAlbums(boolean includeArtist);    
}
